Skip to content

docs: generate the Omni Helm chart reference from the chart README - #789

Merged
talos-bot merged 2 commits into
siderolabs:mainfrom
Iheanacho-ai:helm-docs
Oct 20, 2026
Merged

docs: generate the Omni Helm chart reference from the chart README#789
talos-bot merged 2 commits into
siderolabs:mainfrom
Iheanacho-ai:helm-docs

Conversation

@Iheanacho-ai

@Iheanacho-ai Iheanacho-ai commented Sep 24, 2026

Copy link
Copy Markdown
Member

What

Adds an Omni Helm Chart reference page, generated from the chart README in siderolabs/omni, and a tool to regenerate it. Closes #333.

Why

The chart docs only existed as a README on GitHub, so readers had to leave the docs site to find install steps and values. As agreed in #333, the README stays the source of truth, and the docs site gets a generated copy that can be refreshed with one command.

Change

  • New tool tools/omni-helm-chart-gen (Go, with tests and a Dockerfile). It fetches the chart README from the latest Omni release tag, or a pinned ref, and converts it to MDX:
    • GitHub alerts become Mintlify callouts.
    • Bare autolinks become Markdown links.
    • Relative values.yaml links point to GitHub.
    • The title, badges, homepage line and Maintainers section are dropped.
  • New workflow build-omni-helm-chart-gen.yaml publishes the tool's image to ghcr.io.
  • Makefile: adds generate-omni-helm-chart-reference (container) and -local, both taking OMNI_HELM_CHART_REF=<tag> to pin a version. Both are included in generate-omni-reference and generate-omni-reference-local.
  • New page public/omni/reference/helm-chart.mdx, added to the Omni Reference nav, with docs.json regenerated.
  • Repointed three GitHub README links to the new page, using relative links: one in run-omni-on-k8s.mdx and two in enable-workload-proxy.mdx.
  • Bumped version variables in public/snippets/custom-variables.mdx: omni_release to v1.12.2, and omni_helm_chart_release to 2.12.2. The chart variable was 2.5.10, which installed Omni v1.5.10.

Testing

  • Ran:
    • go test (13 tests)
    • make code-review (golangci-lint, tests, hadolint, checkmake)
    • both generate targets
    • make broken-links, validate-docs-nav, style-check-changed, check-frontmatter-changed, docs.json
  • Where: local checkout, local Mintlify preview, and the tool image built locally.
  • By: Claude Code (agent), reviewed by me.
  • Result:
    • All checks pass. The style check reports 0 errors; the 7 warnings on the new page come from the upstream README's wording.
    • The container and local targets produce identical output.
    • The source README matches the README in the published chart 2.12.2 (helm show readme).
    • The page renders in preview, with all callouts, both tables and the anchors working.
    • The values table covers every chart setting outside config. The chart marks the 26 config.* keys it omits # @ignored, and those are documented on the Omni Configuration reference page.
    • In preview, Run Omni on Kubernetes shows --version 2.12.2, and Run Omni Air-gapped shows v1.12.2.
  • Filled from outside the page: the chart has moved from deploy/helm/v2/omni, the path in the issue, to deploy/helm/omni.
  • Follow-up: the container target needs the image, which is published after merge. Until then, use -local or make build-omni-helm-chart-gen-container.

@github-project-automation github-project-automation Bot moved this to To Do in Planning Sep 24, 2026
@talos-bot talos-bot moved this from To Do to In Review in Planning Sep 24, 2026
@github-actions

github-actions Bot commented Sep 24, 2026 •
edited
Loading

Copy link
Copy Markdown

📋 Automated documentation review

An automated pass runs on documentation changes in every PR. The items below are suggestions to consider — advisory, not a merge gate.

Reviewed commit b1cf966 · 🔴 0 critical · 🟡 4 warning(s) · ⚪ 2 notice(s)

  • 🟡 public/omni/reference/helm-chart.mdx:40 — Helm install/upgrade examples pin chart 2.7.2 while the page documents chart v1.12.2 values
    • Why: The page is generated from the v1.12.2 chart README and lists 1.12.x defaults, but the install and upgrade commands use --version 2.7.2, which by the page's own mapping installs Omni v1.7.2. The command works, so readers silently get an Omni several minor versions older than the values documented here.
    • Fix: helm install omni oci://ghcr.io/siderolabs/charts/omni --version 2.12.2 -n omni --create-namespace -f values.yaml
  • 🟡 public/omni/reference/helm-chart.mdx:138 — Link points at the legacy omni.siderolabs.com/docs/how-to-guides path, which has no redirect
    • Why: The page it links to now lives in this repo at public/omni/cluster-management/expose-a-workload-via-service-proxy.mdx, and the only redirect in common.yaml covers /omni/cluster-management/expose-an-http-service-from-a-cluster, not the /docs/how-to-guides/ path, so the link very likely 404s. I could not fetch the live site to confirm since WebFetch is limited to GitHub.
    • Fix: For details on exposing services, see Expose a Workload via Service Proxy.
  • 🟡 public/omni/reference/helm-chart.mdx:1 — New page is not listed in omni.yaml or docs.json, so the new cross-links will 404
    • Why: The Reference group in omni.yaml uses an explicit pages list rather than folder scanning and does not include helm-chart.mdx, and public/docs.json has no helm-chart entry, so the page is unpublished and the links added in run-omni-on-k8s.mdx and enable-workload-proxy.mdx break; the nav and docs.json CI checks would also fail. Disregard if the PR already updates those files, which were not shown to me.
    • Fix: Add - "helm-chart.mdx" to the Reference group pages in omni.yaml and run make docs.json, committing the regenerated public/docs.json
  • 🟡 public/omni/reference/helm-chart.mdx:6 — Header comment names a make target that does not exist
    • Why: The Makefile has generate-omni-cli-reference, generate-omni-config-reference and generate-omni-image-factory-reference but no generate-omni-helm-chart-reference, so a contributor following the regeneration instruction gets 'No rule to make target'.
    • Fix: Add a generate-omni-helm-chart-reference target to the Makefile (and to the generate-omni-reference aggregate), or reference the command that actually regenerates this page

Notices, and the reviewer's full report, are in the run's doc-accuracy-report artifact.

@smira smira removed this from Planning Sep 24, 2026
sterlingkoch
sterlingkoch reviewed Sep 30, 2026
View reviewed changes
Comment thread public/snippets/custom-variables.mdx Outdated
Comment thread tools/omni-helm-chart-gen/main.go
Comment thread tools/omni-helm-chart-gen/main.go
Comment thread public/omni/reference/helm-chart.mdx Outdated
sterlingkoch
sterlingkoch reviewed Oct 2, 2026
View reviewed changes
Comment thread public/omni/reference/helm-chart.mdx Outdated
@github-actions

github-actions Bot commented Oct 20, 2026 •
edited
Loading

Copy link
Copy Markdown

📋 Automated documentation review

⚠️ The reviewer did not finish on commit c94ce15 (it timed out or errored) — see the workflow run log. This run did not produce a result; any findings from an earlier run on this PR still stand.

Iheanacho-ai and others added 2 commits October 20, 2026 15:56
@Iheanacho-ai
docs: generate the Omni Helm chart reference from the chart README
8acb619 
Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
@sterlingkoch @Iheanacho-ai
docs: map retired Omni docs links in the Helm chart reference to curr…
c94ce15 
…ent pages

The chart README links to omni.siderolabs.com/docs, which now redirects
every page to the Omni overview. The generator rewrites mapped links to
their current paths on this site and fails on any it has no mapping for.

Signed-off-by: Sterling Koch <sterling.koch@siderolabs.com>
@Iheanacho-ai

Iheanacho-ai commented Oct 20, 2026

Copy link
Copy Markdown
Member Author

/m

@talos-bot
talos-bot merged commit c94ce15 into siderolabs:main Oct 20, 2026
3 checks passed

This branch was successfully deployed

1 active deployment
staging - public — c94ce15b Deployed Oct 20, 2026 by mintlify[bot]
View deployment
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@sterlingkoch sterlingkoch sterlingkoch approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Pull helm chart docs into the docs repo/website

4 participants

@Iheanacho-ai @sterlingkoch @smira @talos-bot